Actions

A Web API definition can include multiple Actions, each one representing a different request to a specific endpoint using the required HTTP method. All configured actions for an API display in the navigation tree and are listed in the main screen when the Actions node is selected.

Click Add Action to create a new action for an API definition and configure the associated parameters.

Basic API definition settings

Add a name and description and apply action specific settings.

Name

A unique name for the action. The name is used when selecting business objects for actions in Process and Object Studio.

Description

An optional description to provide more information about the action.

Enabled

Actions must be enabled to be available for selection in objects and processes.

Enable Request Data Output Parameter

When selected, creates a Request Data output for an action in Process and Object Studio. When an action runs, the associated data item is populated with the API request data.

Disable Sending of Request

When this option is selected, the request data is generated but the request is not sent to the server. Use in conjunction with Enable Request Data Output Parameter to generate a request without contacting the server, providing a mechanism for debugging and evaluating requests.

Parameters (action-specific)

These parameters are specific to the action and are used in combination with the common parameters as the inputs for an action in objects and processes. When enclosed in square brackets, parameter names are used dynamically to add their values to URLs, header values, and request bodies.

For more information, see Parameters.

Request

Define the HTTP Request that will made to this API endpoint by selecting the required HTTP method and adding the URL path, body content, and headers.

Method

The HTTP method used for the request. The drop-down contains the standard HTTP methods but any request verbs can be entered into the free-text field. Validation is performed on the field to prevent the input of non-allowed characters.

URL Path

The URL path particular to the action that defines the specific request when used with the base URL. The URL path can be parameterized using common and request-specific parameters, enclosed in square brackets.

For example, the base URL is:

http://staff.database.com

The URL Path is:

/api/[version]/employee/[id]

When the parameters are expanded and added to the base URL, a request is made to this address:

http://staff.database.com/api/v1/employee/26855

Body Content

Configure the content to be sent with the HTTP request using one of the following content types:

  • None – The request does not include body content. This is usual for actions that retrieve information, such as those using the GET method.
  • Template – Send text-based body content such JSON or XML. Parameters can be used to add data to the request body.
  • Single File – Send files as part of the API request. The API definition specifies an input parameter that is used to reference a file from a data stage in a process.
  • Multiple Files – Send multiple files as part of the API request. The API definition specifies an input parameter that is used to reference files from a collection stage in a process.
  • Custom Code – For complex scenarios the request body can be generated using code. Where required, this can incorporate code from the Common Code area of the API definition.

Headers (action-specific)

Add a name and value for each header specific to this action. The headers used in a request are a combination of the common headers in the API definition and the headers set at action level. If an action-specific header has the same name as a common header, the value of the action specific is used in any requests.

For further information, see Headers.

Response

Transform the HTTP response using JSONPath or custom code to extract the required data. The data can be stored in data items, making it easier to use in other stages of an object or process. Custom code can be used to configure more complex responses, for example, performing calculations on the response data.

The response output is defined using the following fields:

  • Parameter – The name of the output parameter created to store the data specified.
  • Data Type – The data type of the output parameter.
  • Method – The method can be either JSON Path or Custom Code. If using Custom Code, the outputs are ref parameters that need to be assigned.

  • JSON Path – If using JSON Path, the expression needs to extract specific elements of the JSON into output parameters. These output parameters have a specified Blue Prism data type, and the object found using the JSONPath will be converted to that data type.

    For further information about configuring responses, see Extract response data with JSONPath.

Error handling

If the HTTP request times out, or the response status code indicates a problem with the request (4xx) or a server error (5xx), an exception will be thrown and the Web API Action stage will not produce output parameters. When using a Web API Action stage, the process designer should handle these exceptions using the existing error handing mechanisms (Block, Recover, and Resume). The error message generated from a Web API exception is written in a standard format, containing the HTTP response status, headers, and body. The process designer can parse this message and add logic to handle specific HTTP status codes as required.